Expand documentation on integration tests

diff --git a/src/doc/manifest.md b/src/doc/manifest.md
index d30001fef81bb21b8150283b1b91716dfd2cffd4..cebdee06146bad0e143d2a7befe6d3a623c7bab3 100644 (file)
--- a/src/doc/manifest.md
+++ b/src/doc/manifest.md
@@ -428,11 +428,22 @@ When you run `cargo test`, Cargo will:
   `lib.rs`. Any sections marked with `#[cfg(test)]` will be included.
 * Compile and run your library’s documentation tests, which are embedded
   inside of documentation blocks.
-* Compile and run your library's integration tests, which are located in
-  `tests`. Files in `tests` load in your library by using `extern crate
-  <library-name>` like any other code that depends on it.
+* Compile and run your library's [integration tests](#integration-tests).
 * Compile your library's examples.
 
+## Integration tests
+
+Each file in `tests/*.rs` is an integration test. When you run `cargo test`,
+Cargo will compile each of these files as a separate crate. The crate can link
+to your library by using `extern crate <library-name>`, like any other code
+that depends on it.
+
+Cargo will not automatically compile files inside subdirectories of `tests`,
+but an integration test can import modules from these directories as usual.
+For example, if you want several integration tests to share some code, you can
+put the shared code in `tests/common/mod.rs` and then put `mod common;` in
+each of the test files.
+
 # Configuring a target
 
 All of the  `[[bin]]`, `[lib]`, `[[bench]]`, and `[[test]]` sections support